Color Contexts
-<!-- ##### SECTION ./tmpl/cursors.sgml:Long_Description ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/cursors.sgml:See_Also ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/cursors.sgml:Short_Description ##### -->
-standard and pixmap cursors.
-
-
-<!-- ##### SECTION ./tmpl/cursors.sgml:Title ##### -->
-Cursors
-
-
-<!-- ##### SECTION ./tmpl/dnd.sgml:Long_Description ##### -->
-<para>
-These functions provide a low level interface for drag and drop.
-GDK supports both the Xdnd and Motif drag and drop protocols transparently.
-</para>
-<para>
-GTK+ provides a higher level abstraction based on top of these functions,
-and so they are not normally needed in GTK+ applications.
-See the <link linkend="gtk-Drag-and-Drop">Drag and Drop</link> section of
-the GTK+ documentation for more information.
-</para>
-
-
-<!-- ##### SECTION ./tmpl/dnd.sgml:See_Also ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/dnd.sgml:Short_Description ##### -->
-functions for controlling drag and drop handling.
-
-
-<!-- ##### SECTION ./tmpl/dnd.sgml:Title ##### -->
-Drag and Drop
-
-
-<!-- ##### SECTION ./tmpl/drawing.sgml:Long_Description ##### -->
-<para>
-These functions provide support for drawing points, lines, arcs and text
-onto what are called 'drawables'. Drawables, as the name suggests, are things
-which support drawing onto them, and are either #GdkWindow or #GdkPixmap
-objects.
-</para>
-<para>
-Many of the drawing operations take a #GdkGC argument, which represents a
-graphics context. This #GdkGC contains a number of drawing attributes such
-as foreground color, background color and line width, and is used to reduce
-the number of arguments needed for each drawing operation. See the
-<link linkend="gdk-Graphics-Contexts">Graphics Contexts</link> section for
-more information.
-</para>
-
-
-<!-- ##### SECTION ./tmpl/drawing.sgml:See_Also ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/drawing.sgml:Short_Description ##### -->
-functions for drawing points, lines, arcs, and text.
-
-
-<!-- ##### SECTION ./tmpl/drawing.sgml:Title ##### -->
-Drawing Primitives
-
-
-<!-- ##### SECTION ./tmpl/event_structs.sgml:Long_Description ##### -->
-<para>
-The event structs contain data specific to each type of event in GDK.
-</para>
-<note>
-<para>
-A common mistake is to forget to set the event mask of a widget so that the
-required events are received. See gtk_widget_set_events().
-</para>
-</note>
-
-
-<!-- ##### SECTION ./tmpl/event_structs.sgml:See_Also ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/event_structs.sgml:Short_Description ##### -->
-data structures specific to each type of event.
-
-
-<!-- ##### SECTION ./tmpl/event_structs.sgml:Title ##### -->
-Event Structures
-
-
-<!-- ##### SECTION ./tmpl/events.sgml:Long_Description ##### -->
-<para>
-This section describes functions dealing with events from the window system.
-</para>
-<para>
-In GTK+ applications the events are handled automatically in
-gtk_main_do_event() and passed on to the appropriate widgets, so these
-functions are rarely needed. Though some of the fields in the
-<link linkend="gdk-Event-Structures">Event Structures</link> are useful.
-</para>
-
-
-<!-- ##### SECTION ./tmpl/events.sgml:See_Also ##### -->
-<para>
-<variablelist>
-<varlistentry>
-<term><link linkend="gdk-Event-Structures">Event Structures</link></term>
-<listitem><para>
-The structs used for each type of event.
-</para></listitem>
-</varlistentry>
-</variablelist>
-</para>
-
-
-<!-- ##### SECTION ./tmpl/events.sgml:Short_Description ##### -->
-functions for handling events from the window system.
-
-
-<!-- ##### SECTION ./tmpl/events.sgml:Title ##### -->
-Events
-
-
-<!-- ##### SECTION ./tmpl/fonts.sgml:Long_Description ##### -->
-<para>
-The GdkFont data type represents a font for drawing on
-the screen. These functions provide support for
-loading fonts, and also for determining the dimensions
-of characters and strings when drawn with a particular
-font.
-</para>
-
-<para>
-Fonts in X are specified by a
-<firstterm>X Logical Font Description</firstterm>.
-The following description is considerably simplified.
-For definitive information about XLFD's see the
-X reference documentation. A X Logical Font Description (XLFD)
-consists of a sequence of fields separated (and surrounded by) '-'
-characters. For example, Adobe Helvetica Bold 12 pt, has the
-full description:
-
-<programlisting>
-"-adobe-helvetica-bold-r-normal--12-120-75-75-p-70-iso8859-1"
-</programlisting>
-</para>
-
-<para>
-The fields in the XLFD are:
-
-<informaltable pgwide=1 frame="none">
-<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
-<tbody>
-
-<row>
-<entry>Foundry</entry>
-<entry>the company or organization where the font originated.</entry>
-</row>
-
-<row>
-<entry>Family</entry>
-<entry>the font family (a group of related font designs).</entry>
-</row>
-
-<row>
-<entry>Weight</entry>
-<entry>A name for the font's typographic weight
-For example, 'bold' or 'medium').</entry>
-</row>
-
-<row>
-<entry>Slant</entry>
-<entry>The slant of the font. Common values are 'R' for Roman,
-'I' for italoc, and 'O' for oblique.</entry>
-</row>
-
-<row>
-<entry>Set Width</entry>
-<entry>A name for the width of the font. For example,
-'normal' or 'condensed'.</entry>
-</row>
-
-<row>
-<entry>Add Style</entry>
-<entry>Additional information to distinguish a font from
-other fonts of the same family.</entry>
-</row>
-
-<row>
-<entry>Pixel Size</entry>
-<entry>The body size of the font in pixels.</entry>
-</row>
-
-<row>
-<entry>Point Size</entry>
-<entry>The body size of the font in 10ths of a point.
-(A <firstterm>point</firstterm> is 1/72.27 inch) </entry>
-</row>
-
-<row>
-<entry>Resolution X</entry>
-<entry>The horizontal resolution that the font was designed for.</entry>
-</row>
-
-<row>
-<entry>Resolution Y</entry>
-<entry>The vertical resolution that the font was designed for .</entry>
-</row>
-
-<row>
-<entry>Spacing</entry>
-<entry>The type of spacing for the font - can be 'p' for proportional,
-'m' for monospaced or 'c' for charcell.</entry>
-</row>
-
-<row>
-<entry>Average Width</entry>
-<entry>The average width of a glyph in the font. For monospaced
-and charcell fonts, all glyphs in the font have this width</entry>
-</row>
-
-<row>
-<entry>Charset Registry</entry>
-<entry>The registration authority that owns the encoding for
-the font. Together with the Charset Encoding field, this
-defines the character set for the font.</entry>
-</row>
-
-<row>
-<entry>Charset Encoding</entry>
-<entry>An identifier for the particular character set encoding.</entry>
-</row>
-
-</tbody></tgroup></informaltable>
-</para>
-
-<para>
-When specifying a font via a X logical Font Description,
-'*' can be used as a wildcard to match any portion of
-the XLFD. For instance, the above example could
-also be specified as
-
-<programlisting>
-"-*-helvetica-bold-r-normal--*-120-*-*-*-*-iso8859-1"
-</programlisting>
-
-It is generally a good idea to use wildcards for any
-portion of the XLFD that your program does not care
-about specifically, since that will improve the
-chances of finding a matching font.
-</para>
-
-<para>
-A <firstterm>fontset</firstterm> is a list of fonts
-that is used for drawing international text that may
-contain characters from a number of different character
-sets. It is represented by a list of XLFD's.
-</para>
-
-<para>
-The font for a given character set is determined by going
-through the list of XLFD's in order. For each one, if
-the registry and and encoding fields match the desired
-character set, then that font is used, otherwise if
-the XLFD contains wild-cards for the registry and encoding
-fields, the registry and encoding for the desired character
-set are subsituted in and a lookup is done. If a match is found
-that font is used. Otherwise, processing continues
-on to the next font in the list.
-</para>
-
-<para>
-The functions for determining the metrics of a string
-come in several varieties that can take a number
-of forms of string input:
-
-<variablelist>
- <varlistentry>
- <term>8-bit string</term>
- <listitem><para>
- When using functions like gdk_string_width() that
- take a <type>gchar *</type>, if the font is of type
- %GDK_FONT_FONT and is an 8-bit font, then each
- <type>gchar</type> indexes the glyphs in the font directly.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>16-bit string</term>
- <listitem><para>
- For functions taking a <type>gchar *</type>, if the
- font is of type %GDK_FONT_FONT, and is a 16-bit
- font, then the <type>gchar *</type> argument is
- interpreted as a <type>guint16 *</type> cast to
- a <type>gchar *</type> and each <type>guint16</type>
- indexes the glyphs in the font directly.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>Multibyte string</term>
- <listitem><para>
- For functions taking a <type>gchar *</type>, if the
- font is of type %GDK_FONT_FONTSET, then the input
- string is interpreted as a <firstterm>multibyte</firstterm>
- encoded according to the current locale. (A multibyte
- string is one in which each character may consist
- of one or more bytes, with different lengths for different
- characters in the string). They can be converted to and
- from wide character strings (see below) using
- gdk_wcstombs() and gdk_mbstowcs().) The string will
- be rendered using one or more different fonts from
- the fontset.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>Wide character string</term>
- <listitem><para>
- For a number of the text-measuring functions, GTK+
- provides a variant (such as gdk_text_width_wc()) which
- takes a <type>GdkWChar *</type> instead of a
- <type>gchar *</type>. The input is then taken to
- be a wide character string in the encoding of the
- current locale. (A wide character string is a string
- in which each character consists of several bytes,
- and the width of each character in the string is
- constant.)
- </para></listitem>
- </varlistentry>
-</variablelist>
-</para>
-
-<para>
-GDK provides functions to determine a number of different
-measurements (metrics) for a given string. (Need diagram
-here).
-
-<variablelist>
- <varlistentry>
- <term>ascent</term>
- <listitem><para>
- The vertical distance from the origin of the drawing
- opereration to the top of the drawn character.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>descent</term>
- <listitem><para>
- The vertical distance from the origin of the drawing
- opereration to the bottom of the drawn character.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>left bearing</term>
- <listitem><para>
- The horizontal distance from the origin of the drawing
- operation to the left-most part of the drawn character.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>right bearing</term>
- <listitem><para>
- The horizontal distance from the origin of the drawing
- operation to the right-most part of the drawn character.
- </para></listitem>
- </varlistentry>
- <varlistentry>
- <term>width bearing</term>
- <listitem><para>
- The horizontal distance from the origin of the drawing
- operation to the correct origin for drawing another
- string to follow the current one. Depending on the
- font, this could be greater than or less than the
- right bearing.
- </para></listitem>
- </varlistentry>
-</variablelist>
-</para>
-
-
-<!-- ##### SECTION ./tmpl/fonts.sgml:See_Also ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/fonts.sgml:Short_Description ##### -->
-loading and manipulating fonts
-
-
-<!-- ##### SECTION ./tmpl/fonts.sgml:Title ##### -->
-Fonts
-
-
-<!-- ##### SECTION ./tmpl/gcs.sgml:Long_Description ##### -->
-<para>
-All drawing operations in GDK take a
-<firstterm>graphics context</firstterm> (GC) argument.
-A graphics context encapsulates information about
-the way things are drawn, such as the foreground
-color or line width. By using graphics contexts,
-the number of arguments to each drawing call is
-greatly reduced, and communication overhead is
-minimized, since identical arguments do not need
-to be passed repeatedly.
-</para>
-<para>
-Most values of a graphics context can be set at
-creation time by using gdk_gc_new_with_values(),
-or can be set one-by-one using functions such
-as gdk_gc_set_foreground(). A few of the values
-in the GC, such as the dash pattern, can only
-be set by the latter method.
-</para>
-
-
-<!-- ##### SECTION ./tmpl/gcs.sgml:See_Also ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/gcs.sgml:Short_Description ##### -->
-objects to encapsulate drawing properties.
-
-
-<!-- ##### SECTION ./tmpl/gcs.sgml:Title ##### -->
-Graphics Contexts
-
-
<!-- ##### SECTION ./tmpl/gdkkeys.sgml:Long_Description ##### -->
<para>
Points, Rectangles and Regions
-<!-- ##### SECTION ./tmpl/input.sgml:Long_Description ##### -->
-<para>
-The functions in this section are used to establish
-callbacks when some condition becomes true for
-a file descriptor. They are currently just wrappers around
-the <link linkend="glib-IO-Channels">IO Channel</link>
-facility.
-</para>
-
-
-<!-- ##### SECTION ./tmpl/input.sgml:See_Also ##### -->
-<para>
-<variablelist>
-
-<varlistentry>
-<term><link linkend="glib-The-Main-Event-Loop">GLib Main Loop</link></term>
-<listitem><para>The main loop in which input callbacks run.</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><link linkend="glib-IO-Channels">IO Channels</link></term>
-<listitem><para>A newer and more flexible way of doing IO
-callbacks.</para></listitem>
-</varlistentry>
-
-</variablelist>
-</para>
-
-
-<!-- ##### SECTION ./tmpl/input.sgml:Short_Description ##### -->
-Callbacks on file descriptors.
-
-
-<!-- ##### SECTION ./tmpl/input.sgml:Title ##### -->
-Input
-
-
-<!-- ##### SECTION ./tmpl/input_contexts.sgml:Long_Description ##### -->
-<para>
-A #GdkIC input context is used for each user interface element which supports
-internationalized text input. See the
-<link linkend="gdk-Input-Methods">Input Methods</link> section for an overview
-of how internationalized text input works in GTK+.
-</para>
-
-
-<!-- ##### SECTION ./tmpl/input_contexts.sgml:See_Also ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/input_contexts.sgml:Short_Description ##### -->
-internationalized text input properties.
-
-
-<!-- ##### SECTION ./tmpl/input_contexts.sgml:Title ##### -->
-Input Contexts
-
-
-<!-- ##### SECTION ./tmpl/input_devices.sgml:Long_Description ##### -->
-<para>
-In addition to the normal keyboard and mouse input devices, GTK+ also
-contains support for <firstterm>extended input devices</firstterm>. In
-particular, this support is targeted at graphics tablets. Graphics
-tablets typically return sub-pixel positioning information and possibly
-information about the pressure and tilt of the stylus. Under
-X, the support for extended devices is done through the
-<firstterm>XInput</firstterm> extension.
-</para>
-<para>
-Because handling extended input devices may involve considerable
-overhead, they need to be turned on for each #GdkWindow
-individually using gdk_input_set_extension_events().
-(Or, more typically, for GtkWidgets, using gtk_widget_set_extension_events()).
-As an additional complication, depending on the support from
-the windowing system, its possible that a normal mouse
-cursor will not be displayed for a particular extension
-device. If an application does not want to deal with displaying
-a cursor itself, it can ask only to get extension events
-from devices that will display a cursor, by passing the
-%GDK_EXTENSION_EVENTS_CURSOR value to
-gdk_input_set_extension_events(). Otherwise, the application
-must retrieve the device information using gdk_input_list_devices(),
-check the <structfield>has_cursor</structfield> field, and,
-if it is %FALSE, draw a cursor itself when it receives
-motion events.
-</para>
-<para>
-Each pointing device is assigned a unique integer ID; events from a
-particular device can be identified by the
-<structfield>deviceid</structfield> field in the event structure. The
-events generated by pointer devices have also been extended to contain
-<structfield>pressure</structfield>, <structfield>xtilt</structfield>
-and <structfield>ytilt</structfield> fields which contain the extended
-information reported as additional <firstterm>valuators</firstterm>
-from the device. The <structfield>pressure</structfield> field is a
-a double value ranging from 0.0 to 1.0, while the tilt fields are
-double values ranging from -1.0 to 1.0. (With -1.0 representing the
-maximum title to the left or up, and 1.0 representing the maximum
-tilt to the right or down.)
-</para>
-<para>
-One additional field in each event is the
-<structfield>source</structfield> field, which contains an
-enumeration value describing the type of device; this currently
-can be one of
-%GDK_SOURCE_MOUSE,
- %GDK_SOURCE_PEN,
-%GDK_SOURCE_ERASER,
-or %GDK_SOURCE_CURSOR. This field is present to allow simple
-applications to (for instance) delete when they detect eraser
-devices without having to keep track of complicated per-device
-settings.
-</para>
-<para>
-Various aspects of each device may be configured. The easiest way of
-creating a GUI to allow the user to conifigure such a device
-is to use to use the #GtkInputDialog widget in GTK+.
-However, even when using this widget, application writers
-will need to directly query and set the configuration parameters
-in order to save the state between invocations of the application.
-The configuration of devices is queried using gdk_input_list_devices.
-Each device must is activated using gdk_input_set_mode(), which
-also controls whether the device's range is mapped to the
-entire screen or to a single window. The mapping of the valuators of
-the device onto the predefined valuator types is set using
-gdk_input_set_axes. And the source type for each device
-can be set with gdk_input_set_source().
-</para>
-<para>
-Devices may also have associated <firstterm>keys</firstterm>
-or macro buttons. Such keys can be globally set to map
-into normal X keyboard events. The mapping is set using
-gdk_input_set_key().
-</para>
-<para>
-The interfaces in this section will most likely be considerably
-modified in the future to accomodate devices that may have different
-sets of additional valuators than the pressure xtilt and ytilt.
-</para>
-
-
-<!-- ##### SECTION ./tmpl/input_devices.sgml:See_Also ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/input_devices.sgml:Short_Description ##### -->
-Functions for handling extended input devices.
-
-
-<!-- ##### SECTION ./tmpl/input_devices.sgml:Title ##### -->
-Input Devices
-
-
<!-- ##### SECTION ./tmpl/input_methods.sgml.sgml:Long_Description ##### -->
<para>
Pango Interaction
-<!-- ##### SECTION ./tmpl/input_methods.sgml:Long_Description ##### -->
-<para>
-Input Methods provide a way for complex character sets to be used in GTK+.
-Languages such as Chinese, Japanese, and Korean (often abbreviated to CJK)
-use a large number of ideographs, making it impossible to support all
-characters with a simple keyboard. Instead, text is usually
-<emphasis>pre-edited</emphasis> using a phonetic alphabet and then
-<emphasis>composed</emphasis> to form the ideographs.
-</para>
-<para>
-GTK+ makes use of the input method mechanism provided by the X Windows
-platform. When a GTK+ application is started, it opens a connection to the
-input method appropriate for the current locale (if any).
-</para>
-<para>
-Widgets which handle textual input, such as #GtkEntry, need to do a number of
-things to support internationalized text input:
-<variablelist>
-<varlistentry>
-<term>When the widget is realized:</term>
-<listitem><para>Check if an input method is being used with gdk_im_ready().
-If it is, create a new <link linkend="gdk-Input-Contexts">Input Context</link>
-using gdk_ic_new(). Find out which events the
-<link linkend="gdk-Input-Contexts">Input Context</link> needs to receive
-with gdk_ic_get_events(), and make sure that the widget's window receives
-these events using gdk_window_set_events().
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>When the widget's size, state or cursor position changes:</term>
-<listitem><para>
-Update the appropriate
-<link linkend="gdk-Input-Contexts">Input Context</link> attributes
-using gdk_ic_set_attr().
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>When the keyboard focus enters or leaves the widget:</term>
-<listitem><para>
-Call gdk_im_begin() or gdk_im_end() to start or finish editing the text.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>When the widget receives a key_press event:</term>
-<listitem><para>
-The <structfield>string</structfield> and <structfield>length</structfield>
-fields of the #GdkEventKey struct should be used to insert the composed text
-into the widget.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>When the widget is unrealized:</term>
-<listitem><para>
-Destroy the <link linkend="gdk-Input-Contexts">Input Context</link>.
-</para></listitem>
-</varlistentry>
-</variablelist>
-
-</para>
-<para>
-See the XLib reference manual for more detailed information on input methods,
-and the #GtkEntry and #GtkText widgets for some example code.
-</para>
-
-
-<!-- ##### SECTION ./tmpl/input_methods.sgml:See_Also ##### -->
-<para>
-<variablelist>
-<varlistentry>
-<term><link linkend="gdk-Input-Contexts">Input Contexts</link></term>
-<listitem><para>
-Used for each widget that handles internationalized text input using the
-global input method.
-</para></listitem>
-</varlistentry>
-</variablelist>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/input_methods.sgml:Short_Description ##### -->
-support for internationalized text input.
-
-
-<!-- ##### SECTION ./tmpl/input_methods.sgml:Title ##### -->
-Input Methods
-
-
-<!-- ##### SECTION ./tmpl/keys.sgml:Long_Description ##### -->
-<para>
-Key values are the codes which are sent whenever a key is pressed or released.
-They appear in the <structfield>keyval</structfield> field of the
-#GdkEventKey structure, which is passed to signal handlers for the
-"key-press-event" and "key-release-event" signals.
-The complete list of key values can be found in the <gdk/gdkkeysyms.h>
-header file.
-</para>
-<para>
-Key values can be converted into a string representation using
-gdk_keyval_name(). The reverse function, converting a string to a key value,
-is provided by gdk_keyval_from_name().
-</para>
-<para>
-The case of key values can be determined using gdk_keyval_is_upper() and
-gdk_keyval_is_lower(). Key values can be converted to upper or lower case
-using gdk_keyval_to_upper() and gdk_keyval_to_lower().
-</para>
-
-
-<!-- ##### SECTION ./tmpl/keys.sgml:See_Also ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/keys.sgml:Short_Description ##### -->
-functions for manipulating keyboard codes.
-
-
-<!-- ##### SECTION ./tmpl/keys.sgml:Title ##### -->
-Key Values
-
-
-<!-- ##### SECTION ./tmpl/pango_interaction.sgml:Long_Description ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/pango_interaction.sgml:See_Also ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/pango_interaction.sgml:Short_Description ##### -->
-
-
-
-<!-- ##### SECTION ./tmpl/pango_interaction.sgml:Title ##### -->
-Pango Interaction
-
-
-<!-- ##### SECTION ./tmpl/properties.sgml:Long_Description ##### -->
-<para>
-Each window under X can have any number of associated
-<firstterm>properties</firstterm> attached to it.
-Properties are arbitrary chunks of data identified by
-<firstterm>atom</firstterm>s. (An <firstterm>atom</firstterm>
-is a numeric index into a string table on the X server. They are used
-to transfer strings efficiently between clients without
-having to transfer the entire string.) A property
-has an associated type, which is also identified
-using an atom.
-</para>
-<para>
-A property has an associated <firstterm>format</firstterm>,
-an integer describing how many bits are in each unit
-of data inside the property. It must be 8, 16, or 32.
-When data is transfered between the server and client,
-if they are of different endianesses it will be byteswapped
-as necessary according to the format of the property.
-Note that on the client side, properties of format 32
-will be stored with one unit per <emphasis>long</emphasis>,
-even if a long integer has more than 32 bits on the platform.
-(This decision was apparently made for Xlib to maintain
-compatibility with programs that assumed longs were 32
-bits, at the expense of programs that knew better.)
-</para>
-<para>
-The functions in this section are used to add, remove
-and change properties on windows, to convert atoms
-to and from strings and to manipulate some types of
-data commonly stored in X window properties.
-</para>
-
-
-<!-- ##### SECTION ./tmpl/properties.sgml:See_Also ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/properties.sgml:Short_Description ##### -->
-functions to manipulate properties on windows.
-
-
-<!-- ##### SECTION ./tmpl/properties.sgml:Title ##### -->
-Properties and Atoms
-
-
-<!-- ##### SECTION ./tmpl/regions.sgml:Long_Description ##### -->
-<para>
-GDK provides the #GdkPoint, #GdkRectangle, #GdkRegion and #GdkSpan data types
-for representing pixels and sets of pixels on the screen.
-</para>
-<para>
-#GdkPoint is a simple structure containing an x and y coordinate of a point.
-</para>
-<para>
-#GdkRectangle is a structure holding the position and size of a rectangle.
-The intersection of two rectangles can be computed with
-gdk_rectangle_intersect(). To find the union of two rectangles use
-gdk_rectangle_union().
-</para>
-<para>
-#GdkRegion is an opaque data type holding a set of arbitrary pixels, and is
-usually used for clipping graphical operations (see gdk_gc_set_clip_region()).
-</para>
-<para>
-#GdkSpan is a structure holding a spanline. A spanline is a horizontal line that
-is one pixel wide. It is mainly used when rasterizing other graphics primitives.
-It can be intersected to regions by using gdk_region_spans_intersect_foreach().
-</para>
-
-
-<!-- ##### SECTION ./tmpl/regions.sgml:See_Also ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/regions.sgml:Short_Description ##### -->
-simple graphical data types.
-
-
-<!-- ##### SECTION ./tmpl/regions.sgml:Title ##### -->
-Points, Rectangles and Regions
-
-
<!-- ##### SECTION ./tmpl/regions2.sgml:Long_Description ##### -->
<para>
GDK provides the #GdkPoint, #GdkRectangle and #GdkRegion data types for
Points, Rectangles and Regions
-<!-- ##### SECTION ./tmpl/selections.sgml:Long_Description ##### -->
-<para>
-The X selection mechanism provides a way to transfer
-arbitrary chunks of data between programs.
-A <firstterm>selection</firstterm> is a essentially
-a named clipboard, identified by a string interned
-as a #GdkAtom. By claiming ownership of a selection,
-an application indicates that it will be responsible
-for supplying its contents. The most common
-selections are <literal>PRIMARY</literal> and
-<literal>CLIPBOARD</literal>.
-</para>
-<para>
-The contents of a selection can be represented in
-a number of formats, called <firstterm>targets</firstterm>.
-Each target is identified by an atom. A list of
-all possible targets supported by the selection owner
-can be retrieved by requesting the special target
-<literal>TARGETS</literal>. When a selection is
-retrieved, the data is accompanied by a type
-(an atom), and a format (an integer, representing
-the number of bits per item).
-See <link linkend="gdk-Properties-and-Atoms">Properties and Atoms</link>
-for more information.
-</para>
-<para>
-The functions in this section only contain the lowlevel
-parts of the selection protocol. A considerably more
-complicated implementation is needed on top of this.
-GTK+ contains such an implementation in the functions
-in <literal>gtkselection.h</literal> and programmers
-should use those functions instead of the ones presented
-here. If you plan to implement selection handling
-directly on top of the functions here, you should refer
-to the X Inter-client Communication Conventions Manual
-(ICCCM).
-</para>
-
-
-<!-- ##### SECTION ./tmpl/selections.sgml:See_Also ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/selections.sgml:Short_Description ##### -->
-functions for transfering data via the X selection mechanism.
-
-
-<!-- ##### SECTION ./tmpl/selections.sgml:Title ##### -->
-Selections
-
-
-<!-- ##### SECTION ./tmpl/threads.sgml:Long_Description ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/threads.sgml:See_Also ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/threads.sgml:Short_Description ##### -->
-
-
-
-<!-- ##### SECTION ./tmpl/threads.sgml:Title ##### -->
-Threads
-
-
-<!-- ##### SECTION ./tmpl/visuals.sgml:Long_Description ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/visuals.sgml:See_Also ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/visuals.sgml:Short_Description ##### -->
-
-
-
-<!-- ##### SECTION ./tmpl/visuals.sgml:Title ##### -->
-Visuals
-
-
-<!-- ##### SECTION ./tmpl/windows.sgml:Long_Description ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/windows.sgml:See_Also ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/windows.sgml:Short_Description ##### -->
-
-
-
-<!-- ##### SECTION ./tmpl/windows.sgml:Title ##### -->
-Windows
-
-
-<!-- ##### SECTION ./tmpl/x_interaction.sgml:Long_Description ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/x_interaction.sgml:See_Also ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### SECTION ./tmpl/x_interaction.sgml:Short_Description ##### -->
-
-
-
-<!-- ##### SECTION ./tmpl/x_interaction.sgml:Title ##### -->
-X Window System Interaction
-
-
<!-- ##### MACRO GDK_CORE_POINTER ##### -->
<para>
This macro contains an integer value representing
@ytilt: location to store current tilt in the y direction.
@mask: location to store the current modifier state.
+<!-- ##### FUNCTION gdk_key_repeat_disable ##### -->
+<para>
+Disables the keyboard auto-repeat mode.
+This should be used with care as it may affect other applications.
+</para>
+
+
+<!-- ##### FUNCTION gdk_key_repeat_restore ##### -->
+<para>
+Restores the keyboard auto-repeat mode to its state when the application was
+started.
+</para>
+
+
<!-- ##### FUNCTION gdk_regions_intersect ##### -->
<para>
Returns the intersection of two regions.
/* Manipulation of drawables
*/
+/**
+ * gdk_drawable_set_data:
+ * @drawable: a #GdkDrawable
+ * @key: name to store the data under
+ * @data: arbitrary data
+ * @destroy_func: function to free @data, or %NULL
+ *
+ * This function is equivalent to g_object_set_data(),
+ * the #GObject variant should be used instead.
+ *
+ **/
void
gdk_drawable_set_data (GdkDrawable *drawable,
const gchar *key,
destroy_func);
}
+/**
+ * gdk_drawable_get_data:
+ * @drawable: a #GdkDrawable
+ * @key: name the data was stored under
+ *
+ * Equivalent to g_object_get_data(); the #GObject variant should be
+ * used instead.
+ *
+ * Return value: the data stored at @key
+ **/
gpointer
gdk_drawable_get_data (GdkDrawable *drawable,
const gchar *key)
g_quark_try_string (key));
}
+/**
+ * gdk_drawable_get_size:
+ * @drawable: a #GdkDrawable
+ * @width: location to store drawable's width, or %NULL
+ * @height: location to store drawable's height, or %NULL
+ *
+ * Fills *@width and *@height with the size of @drawable.
+ * @width or @height can be %NULL if you only want the other one.
+ *
+ **/
void
gdk_drawable_get_size (GdkDrawable *drawable,
gint *width,
GDK_DRAWABLE_GET_CLASS (drawable)->get_size (drawable, width, height);
}
+/**
+ * gdk_drawable_get_visual:
+ * @drawable: a #GdkDrawable
+ *
+ * Gets the #GdkVisual describing the pixel format of @drawable.
+ *
+ * Return value: a #GdkVisual
+ **/
GdkVisual*
gdk_drawable_get_visual (GdkDrawable *drawable)
{
return GDK_DRAWABLE_GET_CLASS (drawable)->get_visual (drawable);
}
+/**
+ * gdk_drawable_get_depth:
+ * @drawable: a #GdkDrawable
+ *
+ * Obtains the bit depth of the drawable, that is, the number of bits
+ * that make up a pixel in the drawable's visual. Examples are 8 bits
+ * per pixel, 24 bits per pixel, etc.
+ *
+ * Return value: number of bits per pixel
+ **/
gint
gdk_drawable_get_depth (GdkDrawable *drawable)
{
return GDK_DRAWABLE_GET_CLASS (drawable)->get_depth (drawable);
}
+/**
+ * gdk_drawable_set_colormap:
+ * @drawable: a #GdkDrawable
+ * @colormap: a #GdkColormap
+ *
+ * Sets the colormap associated with @drawable. Normally this will
+ * happen automatically when the drawable is created; you only need to
+ * use this function if the drawable-creating function did not have a
+ * way to determine the colormap, and you then use drawable operations
+ * that require a colormap. The colormap for all drawables and
+ * graphics contexts you intend to use together should match. i.e.
+ * when using a #GdkGC to draw to a drawable, or copying one drawable
+ * to another, the colormaps should match.
+ *
+ **/
void
gdk_drawable_set_colormap (GdkDrawable *drawable,
GdkColormap *cmap)
GDK_DRAWABLE_GET_CLASS (drawable)->set_colormap (drawable, cmap);
}
+/**
+ * gdk_drawable_get_colormap:
+ * @drawable: a #GdkDrawable
+ *
+ * Gets the colormap for @drawable, if one is set; returns
+ * %NULL otherwise.
+ *
+ * Return value: the colormap, or %NULL
+ **/
GdkColormap*
gdk_drawable_get_colormap (GdkDrawable *drawable)
{
return GDK_DRAWABLE_GET_CLASS (drawable)->get_colormap (drawable);
}
+/**
+ * gdk_drawable_ref:
+ * @drawable: a #GdkDrawable
+ *
+ * Deprecated equivalent of calling g_object_ref() on @drawable.
+ * (Drawables were not objects in previous versions of GDK.)
+ *
+ * Return value: the same @drawable passed in
+ **/
GdkDrawable*
gdk_drawable_ref (GdkDrawable *drawable)
{
return (GdkDrawable *) g_object_ref (G_OBJECT (drawable));
}
+/**
+ * gdk_drawable_unref:
+ * @drawable: a #GdkDrawable
+ *
+ * Deprecated equivalent of calling g_object_unref() on @drawable.
+ *
+ **/
void
gdk_drawable_unref (GdkDrawable *drawable)
{
}
+/**
+ * gdk_drawable_get_image:
+ * @drawable: a #GdkDrawable
+ * @x: x coordinate on @drawable
+ * @y: y coordinate on @drawable
+ * @width: width of region to get
+ * @height: height or region to get
+ *
+ * A #GdkImage stores client-side image data (pixels). In contrast,
+ * #GdkPixmap and #GdkWindow are server-side
+ * objects. gdk_drawable_get_image() obtains the pixels from a
+ * server-side drawable as a client-side #GdkImage. The format of a
+ * #GdkImage depends on the #GdkVisual of the current display, which
+ * makes manipulating #GdkImage extremely difficult; therefore, in
+ * most cases you should use gdk_pixbuf_get_from_drawable() instead of
+ * this lower-level function. A #GdkPixbuf contains image data in a
+ * canonicalized RGB format, rather than a display-dependent format.
+ * Of course, there's a convenience vs. speed tradeoff here, so you'll
+ * want to think about what makes sense for your application.
+ *
+ * @x, @y, @width, and @height define the region of @drawable to
+ * obtain as an image.
+ *
+ * You would usually copy image data to the client side if you intend
+ * to examine the values of individual pixels, for example to darken
+ * an image or add a red tint. It would be prohibitively slow to
+ * make a round-trip request to the windowing system for each pixel,
+ * so instead you get all of them at once, modify them, then copy
+ * them all back at once.
+ *
+ * If the X server or other windowing system backend is on the local
+ * machine, this function may use shared memory to avoid copying
+ * the image data.
+ *
+ * Return value: a #GdkImage containing the contents of @drawable
+ **/
GdkImage*
gdk_drawable_get_image (GdkDrawable *drawable,
gint x,
return TRUE;
}
+/**
+ * gdk_window_begin_paint_rect:
+ * @window: a #GdkWindow
+ * @rectangle: rectangle you intend to draw to
+ *
+ * A convenience wrapper around gdk_window_begin_paint_region() which
+ * creates a rectangular region for you. See
+ * gdk_window_begin_paint_region() for details.
+ *
+ **/
void
gdk_window_begin_paint_rect (GdkWindow *window,
GdkRectangle *rectangle)
#include "x11/gdkx.h"
#endif
+/**
+ * gdk_window_begin_paint_region:
+ * @window: a #GdkWindow
+ * @region: region you intend to draw to
+ *
+ * Indicates that you are beginning the process of redrawing @region.
+ * A backing store (offscreen buffer) large enough to contain @region
+ * will be created. The backing store will be initialized with the
+ * background color or background pixmap for @window. Then, all
+ * drawing operations performed on @window will be diverted to the
+ * backing store. When you call gdk_window_end_paint(), the backing
+ * store will be copied to @window, making it visible onscreen. Only
+ * the part of window contained in @region will be modified; that is,
+ * drawing operations are clipped to @region.
+ *
+ * The net result of all this is to remove flicker, because the user
+ * sees the finished product appear all at once when you call
+ * gdk_window_end_paint(). If you draw to @window directly without
+ * calling gdk_window_begin_paint_region(), the user may see flicker
+ * as individual drawing operations are performed in sequence. The
+ * clipping and background-initializing features of
+ * gdk_window_begin_paint_region() are conveniences for the
+ * programmer, so you can avoid doing that work yourself.
+ *
+ * When using GTK+, the widget system automatically places calls to
+ * gdk_window_begin_paint_region() and gdk_window_end_paint() around
+ * emissions of the expose_event signal. That is, if you're writing an
+ * expose event handler, you can assume that the exposed area in
+ * #GdkEventExpose has already been cleared to the window background,
+ * is already set as the clip region, and already has a backing store.
+ * Therefore in most cases, application code need not call
+ * gdk_window_begin_paint_region(). (You can disable the automatic
+ * calls around expose events on a widget-by-widget basis by calling
+ * gtk_widget_set_double_buffered().)
+ *
+ * If you call this function multiple times before calling the
+ * matching gdk_window_end_paint(), the backing stores are pushed onto
+ * a stack. gdk_window_end_paint() copies the topmost backing store
+ * onscreen, subtracts the topmost region from all other regions in
+ * the stack, and pops the stack. All drawing operations affect only
+ * the topmost backing store in the stack. One matching call to
+ * gdk_window_end_paint() is required for each call to
+ * gdk_window_begin_paint_region().
+ *
+ **/
void
gdk_window_begin_paint_region (GdkWindow *window,
GdkRegion *region)
#endif /* USE_BACKING_STORE */
}
+/**
+ * gdk_window_end_paint:
+ * @window: a #GdkWindow
+ *
+ * Indicates that the backing store created by the most recent call to
+ * gdk_window_begin_paint_region() should be copied onscreen and
+ * deleted, leaving the next-most-recent backing store or no backing
+ * store at all as the active paint region. See
+ * gdk_window_begin_paint_region() for full details. It is an error to
+ * call this function without a matching
+ * gdk_window_begin_paint_region() first.
+ *
+ **/
void
gdk_window_end_paint (GdkWindow *window)
{
if (GDK_WINDOW_DESTROYED (window))
return;
-
- g_return_if_fail (private->paint_stack != NULL);
+
+ if (private->paint_stack == NULL)
+ {
+ g_warning (G_STRLOC": no preceding call to gdk_window_begin_paint_region(), see documentation");
+ return;
+ }
paint = private->paint_stack->data;
private->paint_stack = g_slist_delete_link (private->paint_stack, private->paint_stack);
}
}
+/**
+ * gdk_window_process_all_updates:
+ *
+ * Calls gdk_window_process_updates() for all windows (see #GdkWindow)
+ * in the application.
+ *
+ **/
void
gdk_window_process_all_updates (void)
{
return FALSE;
}
+/**
+ * gdk_window_process_updates:
+ * @window: a #GdkWindow
+ * @update_children: whether to also process updates for child windows
+ *
+ * Sends one or more expose events to @window. The areas in each
+ * expose event will cover the entire update area for the window (see
+ * gdk_window_invalidate_region() for details). Normally GDK calls
+ * gdk_window_process_all_updates() on your behalf, so there's no
+ * need to call this function unless you want to force expose events
+ * to be delivered immediately and synchronously (vs. the usual
+ * case, where GDK delivers them in an idle handler). Occasionally
+ * this is useful to produce nicer scrolling behavior, for example.
+ *
+ **/
void
gdk_window_process_updates (GdkWindow *window,
gboolean update_children)
}
}
+/**
+ * gdk_window_invalidate_rect:
+ * @window: a #GdkWindow
+ * @rect: rectangle to invalidate
+ * @invalidate_children: whether to also invalidate child windows
+ *
+ * A convenience wrapper around gdk_window_invalidate_region() which
+ * invalidates a rectangular region. See
+ * gdk_window_invalidate_region() for details.
+ *
+ **/
void
gdk_window_invalidate_rect (GdkWindow *window,
GdkRectangle *rect,
gdk_region_destroy (region);
}
+/**
+ * gdk_window_invalidate_region:
+ * @window: a #GdkWindow
+ * @region: a #GdkRegion
+ * @invalidate_children: %TRUE to also invalidate child windows
+ *
+ * Adds @region to the update area for @window. The update area is the
+ * region that needs to be redrawn, or "dirty region." The call
+ * gdk_window_process_updates() sends one or more expose events to the
+ * window, which together cover the entire update area. An
+ * application would normally redraw the contents of @window in
+ * response to those expose events.
+ *
+ * GDK will call gdk_window_process_all_updates() on your behalf
+ * whenever your program returns to the main loop and becomes idle, so
+ * normally there's no need to do that manually, you just need to
+ * invalidate regions that you know should be redrawn.
+ *
+ * The @invalidate_children parameter controls whether the region of
+ * each child window that intersects @region will also be invalidated.
+ * If %FALSE, then the update area for child windows will remain
+ * unaffected.
+ *
+ **/
void
gdk_window_invalidate_region (GdkWindow *window,
GdkRegion *region,
gdk_region_destroy (visible_region);
}
+/**
+ * gdk_window_get_update_area:
+ * @window: a #GdkWindow
+ *
+ * Transfers ownership of the update area from @window to the caller
+ * of the function. That is, after calling this function, @window will
+ * no longer have an invalid/dirty region; the update area is removed
+ * from @window and handed to you. If a window has no update area,
+ * gdk_window_get_update_area() returns %NULL. You are responsible for
+ * calling gdk_region_destroy() on the returned region if it's non-%NULL.
+ *
+ * Return value: the update area for @window
+ **/
GdkRegion *
gdk_window_get_update_area (GdkWindow *window)
{
gdk_window_update_idle, NULL, NULL);
}
+/**
+ * gdk_window_set_debug_updates:
+ * @setting: %TRUE to turn on update debugging
+ *
+ * With update debugging enabled, calls to
+ * gdk_window_invalidate_region() clear the invalidated region of the
+ * screen to a noticeable color, and GDK pauses for a short time
+ * before sending exposes to windows during
+ * gdk_window_process_updates(). The net effect is that you can see
+ * the invalid region for each window and watch redraws as they
+ * occur. This allows you to diagnose inefficiencies in your application.
+ *
+ * In essence, because the GDK rendering model prevents all flicker,
+ * if you are redrawing the same region 400 times you may never
+ * notice, aside from noticing a speed problem. Enabling update
+ * debugging causes GTK to flicker slowly and noticeably, so you can
+ * see exactly what's being redrawn when, in what order.
+ *
+ * The --gtk-debug=updates command line option passed to GTK+ programs
+ * enables this debug option at application startup time. That's
+ * usually more useful than calling gdk_window_set_debug_updates()
+ * yourself, though you might want to use this function to enable
+ * updates sometime after application startup time.
+ *
+ **/
void
gdk_window_set_debug_updates (gboolean setting)
{
debug_updates = setting;
}
+
projects / gtk4.git / commitdiff